---
title: Document field
summary: The document field is a highly customisable rich text editor.
---
{% aside icon="⚠️" %}
[`fields.markdoc`](/docs/fields/markdoc) has superseded this field. [`fields.mdx`](/docs/fields/mdx) is also available if you prefer MDX.
{% /aside %}

The `document` field is a highly customisable rich text editor.

It lets content creators quickly and easily edit content in your system.

## Usage example

```ts
document: fields.document({
  label: 'Document',
  formatting: true,
  links: true,
  images: true
})
```

---

## Formatting options

The WYSIWYG toolbar can be customised to allow a range of formatting options. This is done via the `formatting` option on the `document` field.

Setting `formatting: true` will enable all the formatting options that are available in Markdown syntax, but you can also specify only a specific subset of options you want to allow.

The editor features built-in support for some additional common formatting features that require custom Markdoc tags to render, including alignment, underline, subscript and superscript. These aren't included with the shorthand `formatting: true` option, but can be enabled by passing an object with the relevant options set to `true`.

The formatting options enabled when using the shorthand are:

```ts
{
  formatting: {
    inlineMarks: {
      bold: true,
      italic: true,
      strikethrough: true,
      code: true,
    },
    listTypes: {
      ordered: true,
      unordered: true,
    },
    headingLevels: [1, 2, 3, 4, 5, 6],
    blockTypes: {
      blockquote: true,
      code: true,
    },
    softBreaks: true,
  },
}
```

The additional formatting options (not on by default) are:

```ts
{
  formatting: {
    // this is the same as providing `alignment: true`
    alignment: {
      center: true,
      end: true,
    }.
    inlineMarks: {
      keyboard: true,
      subscript: true,
      superscript: true,
      underline: true,
    },
  },
}
```

### Formatting options type signature

The type signature for the full list of available formatting options is available at: [https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document.DocumentFeaturesConfig](https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document.DocumentFeaturesConfig)

---

## Component blocks

The `document` field can register custom component blocks, which you can use to render custom UI components with props within your document field.

Each component block has its own fields schema, and can be configured with a custom preview component.

```ts
document: fields.document({
  label: 'Document',
  formatting: true,
  componentBlocks: {
    quote: component({
      preview: () => null,
      label: 'Quote',
      schema: {
        content: fields.child({
          kind: 'block',
          placeholder: 'Quote...',
          formatting: { inlineMarks: 'inherit', softBreaks: 'inherit' },
          links: 'inherit',
        }),
        attribution: fields.child({ kind: 'inline', placeholder: 'Attribution...' }),
      },
    }),
  },
}),
```

You can nest component blocks within each other by using the [Child field](/docs/fields/child) with the `componentBlocks` property set to `'inherit'`:

```ts
document: fields.document({
  label: 'Document',
  formatting: true,
  componentBlocks: {
    sectionContainer: component({
      // A preview is needed to show the child field
      preview: ({fields}) => (
        <div style={{ padding: '1rem 0' /* styling is up to you */ }}>
          {fields.children.element}
        </div>
      ),
      label: 'Section Container',
      schema: {
        content: fields.child({
          kind: 'block',
          componentBlocks: 'inherit',
          placeholder: 'Add component blocks here...',
        }),
      },
    }),
  },
}),
```

---

## Other configuration options

The `document` field has many more configuration options like `images`, `layouts`, `tables`, `links` or `dividers`.

Here is a more comprehensive example:

```ts
content: fields.document({
  label: 'Content',
  links: true,
  layouts: [[1], [1, 1]],
  images: {
    directory: 'src/content/blog/_images',
    publicPath: '/src/content/blog/_images/',
    schema: {
      title: fields.text({
        label: 'Caption',
        description:
          'The text to display under the image in a caption.',
      }),
    },
  },
  dividers: true,
  formatting: {
    alignment: true,
    blockTypes: true,
    headingLevels: true,
    inlineMarks: {
      code: true,
      bold: true,
      italic: true,
      underline: true,
      strikethrough: true,
    },
    listTypes: true,
  },
  tables: true,
}),
```

---

## Type signature

For the full reference, you can find the latest version of this field's type signature at: [https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document](https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document)
